<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>Hoodoo::Client::Endpoint</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" href="../../../css/reset.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/main.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../../css/github.css" type="text/css" media="screen" />
<script src="../../../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/jquery-effect.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/main.js" type="text/javascript" charset="utf-8"></script>
<script src="../../../js/highlight.pack.js" type="text/javascript" charset="utf-8"></script>

</head>

<body>
    <div class="banner">
        <h1>
            <span class="type">Class</span>
            Hoodoo::Client::Endpoint
                <span class="parent">&lt;
                    Object
                </span>
        </h1>
        <ul class="files">
            <li><a href="../../../files/lib/hoodoo/client/endpoint/endpoint_rb.html">lib/hoodoo/client/endpoint/endpoint.rb</a></li>
            <li><a href="../../../files/lib/hoodoo/client/endpoint/endpoints/amqp_rb.html">lib/hoodoo/client/endpoint/endpoints/amqp.rb</a></li>
            <li><a href="../../../files/lib/hoodoo/client/endpoint/endpoints/auto_session_rb.html">lib/hoodoo/client/endpoint/endpoints/auto_session.rb</a></li>
            <li><a href="../../../files/lib/hoodoo/client/endpoint/endpoints/http_rb.html">lib/hoodoo/client/endpoint/endpoints/http.rb</a></li>
            <li><a href="../../../files/lib/hoodoo/client/endpoint/endpoints/http_based_rb.html">lib/hoodoo/client/endpoint/endpoints/http_based.rb</a></li>
            <li><a href="../../../files/lib/hoodoo/client/endpoint/endpoints/not_found_rb.html">lib/hoodoo/client/endpoint/endpoints/not_found.rb</a></li>
            <li><a href="../../../files/lib/hoodoo/monkey/patch/newrelic_traced_amqp_rb.html">lib/hoodoo/monkey/patch/newrelic_traced_amqp.rb</a></li>
            <li><a href="../../../files/lib/hoodoo/services/middleware/middleware_rb.html">lib/hoodoo/services/middleware/middleware.rb</a></li>
        </ul>
    </div>
    <div id="bodyContent">
        <div id="content">
    <div class="description">
      
<p>Base class for endpoint code.</p>

<p>This base class defines the API to which subclasses must adhere, so that
endpoint users don&#39;t need to care how the endpoint actually
communicates with a target resource.</p>

<p>ENDPOINTS ARE NOT INTENDED TO BE THREAD SAFE. Whenever you want to use one
from a particular thread, instantiate an endpoint for use by just that
thread. Don&#39;t share instances between threads via e.g. controlling
class instance variables recording a reference to a single endpoint object.</p>

    </div>






    <!-- Namespace -->
    <div class="sectiontitle">Namespace</div>
    <ul>
        <li>
          <span class="type">CLASS</span>
          <a href="Endpoint/AMQP.html">Hoodoo::Client::Endpoint::AMQP</a>
        </li>
        <li>
          <span class="type">CLASS</span>
          <a href="Endpoint/AutoSession.html">Hoodoo::Client::Endpoint::AutoSession</a>
        </li>
        <li>
          <span class="type">CLASS</span>
          <a href="Endpoint/HTTP.html">Hoodoo::Client::Endpoint::HTTP</a>
        </li>
        <li>
          <span class="type">CLASS</span>
          <a href="Endpoint/HTTPBased.html">Hoodoo::Client::Endpoint::HTTPBased</a>
        </li>
        <li>
          <span class="type">CLASS</span>
          <a href="Endpoint/NotFound.html">Hoodoo::Client::Endpoint::NotFound</a>
        </li>
    </ul>


    <!-- Method ref -->
    <div class="sectiontitle">Methods</div>
    <dl class="methods">
        <dt>C</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-configure_with">configure_with</a>,
              </li>
              <li>
                <a href="#method-i-copy_updated_options_to">copy_updated_options_to</a>,
              </li>
              <li>
                <a href="#method-i-create">create</a>
              </li>
          </ul>
        </dd>
        <dt>D</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-delete">delete</a>
              </li>
          </ul>
        </dd>
        <dt>E</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-endpoint_for">endpoint_for</a>
              </li>
          </ul>
        </dd>
        <dt>G</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-generate_404_response_for">generate_404_response_for</a>
              </li>
          </ul>
        </dd>
        <dt>I</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-inject_enumeration_state">inject_enumeration_state</a>
              </li>
          </ul>
        </dd>
        <dt>L</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-list">list</a>
              </li>
          </ul>
        </dd>
        <dt>N</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-new">new</a>
              </li>
          </ul>
        </dd>
        <dt>R</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-response_class_for">response_class_for</a>
              </li>
          </ul>
        </dd>
        <dt>S</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-show">show</a>
              </li>
          </ul>
        </dd>
        <dt>U</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-i-update">update</a>
              </li>
          </ul>
        </dd>
    </dl>








      <!-- Section attributes -->
      <div class="sectiontitle">Attributes</div>
      <table border='0' cellpadding='5'>
          <tr valign='top' id='attribute-i-interaction'>
            <td class='attr-rw'>
              [R]
            </td>
            <td class='attr-name'>interaction</td>
            <td class='attr-desc'><p>The value of the <code>interaction</code> option key passed to the
constructor. See the constructor and endpoint_for for more.</p></td>
          </tr>
          <tr valign='top' id='attribute-i-locale'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>locale</td>
            <td class='attr-desc'><p>The locale passed to the constructor or some value provided later; a
String, e.g. “en-gb”, or if <code>nil</code>, uses “en-nz” by default.</p></td>
          </tr>
          <tr valign='top' id='attribute-i-resource'>
            <td class='attr-rw'>
              [R]
            </td>
            <td class='attr-name'>resource</td>
            <td class='attr-desc'><p>The resource name passed to the constructor, as a String.</p></td>
          </tr>
          <tr valign='top' id='attribute-i-session_id'>
            <td class='attr-rw'>
              [RW]
            </td>
            <td class='attr-name'>session_id</td>
            <td class='attr-desc'><p>The session <a href="../UUID.html">UUID</a> passed to the constructor or
some value provided later; used for the calls to the target resource via
the X-Session-ID <a href="Endpoint/HTTP.html">HTTP</a> header or an
equivalent. If <code>nil</code>, only public actions in the target resource
will be accessible.</p></td>
          </tr>
          <tr valign='top' id='attribute-i-version'>
            <td class='attr-rw'>
              [R]
            </td>
            <td class='attr-name'>version</td>
            <td class='attr-desc'><p>The version number passed to the constructor, as an Integer.</p></td>
          </tr>
      </table>


    <!-- Methods -->
      <div class="sectiontitle">Class Public methods</div>
        <div class="method">
          <div class="title method-title" id="method-c-endpoint_for">
              <b>endpoint_for</b>( resource, version, options )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-c-endpoint_for" name="method-c-endpoint_for" class="permalink">Link</a>
          </div>

            <div class="description">
              <p><a href="Endpoint.html">Endpoint</a> factory - instantiates and endpoint
for the given resource and implemented API version, using the given
discoverer.</p>
<dl class="rdoc-list note-list"><dt><code>resource</code>
<dd>
<p>Resource name the endpoint targets, e.g. <code>:Purchase</code>. String or
symbol.</p>
</dd><dt><code>version</code>
<dd>
<p>Optional required interface (API) version for that endpoint. Integer.
Default is 1.</p>
</dd><dt><code>options</code>
<dd>
<p>Options Hash. Options are described below. Note that this Hash may be
modified during processing.</p>
</dd></dl>

<p>Items in the options hash are required, unless explicitly listed as
optional. They are:</p>
<dl class="rdoc-list note-list"><dt><code>discoverer</code>
<dd>
<p>A <a href="../Services/Discovery.html">Hoodoo::Services::Discovery</a>
“By…” family member instance, e.g. a <a
href="../Services/Discovery/ByDRb.html">Hoodoo::Services::Discovery::ByDRb</a>
instance. This is used to look up a service instance. The returned
discovery data type is used to determine the required endpoint type; for
example, a <a
href="../Services/Discovery/ForHTTP.html">Hoodoo::Services::Discovery::ForHTTP</a>
result yields a <a
href="Endpoint/HTTP.html">Hoodoo::Client::Endpoint::HTTP</a> instance.</p>
</dd><dt><code>session_id</code>
<dd>
<p>A session <a href="../UUID.html">UUID</a>, for the X-Session-ID <a
href="Endpoint/HTTP.html">HTTP</a> header or an equivalent. Optional, but
if omitted, only public resource actions will be accessible.</p>
</dd><dt><code>interaction</code>
<dd>
<p>Optional <a
href="../Services/Middleware/Interaction.html">Hoodoo::Services::Middleware::Interaction</a>
instance which describes a <strong>source</strong> interaction at hand.
This is a middleware concept and most of the time, only the middleware
would use this; the middleware is handling some API call which the source
interaction data describes but the resource which is handling the call
needs to make an inter-resource call, which is why an <a
href="Endpoint.html">Endpoint</a> is being created.</p>
</dd><dt><code>locale</code>
<dd>
<p>Locale string for request/response, e.g. “en-gb”. Optional. If omitted,
defaults to “en-nz”.</p>
</dd><dt>OTHERS
<dd>
<p>See Hoodoo::Client::Headers&#39; <code>HEADER_TO_PROPERTY</code>. All such
option keys <em>MUST</em> be Symbols.</p>
</dd></dl>

<p>Returns a <a
href="../Services/Discovery.html">Hoodoo::Services::Discovery</a> “For…”
family member instance (e.g. <a
href="../Services/Discovery/ForHTTP.html">Hoodoo::Services::Discovery::ForHTTP</a>)
which can be used to talk to the resource in question. Getting an instance
does not mean the resource endpoint is found - you will not know that until
you try to talk to it and get a 404 expressed as a platform error in the
response data. See <a
href="AugmentedHash.html">Hoodoo::Client::AugmentedHash</a> and <a
href="AugmentedArray.html">Hoodoo::Client::AugmentedArray</a>.</p>

<p>Callers dealing with inter-resource call code may want to consult their
discoverer to see if the resource is locally available before bothering to
instantiate an endpoint.</p>

<p>If the <code>deja_vu</code> option is set, then a confirmed case of deja vu
results in an empty Hash being returned, with no platform errors
associated. This is the high-level transport neutral equivalent of (say) a
204 <a href="Endpoint/HTTP.html">HTTP</a> response with no body.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-endpoint_for_source')" id="l_method-c-endpoint_for_source">show</a>
              </p>
              <div id="method-c-endpoint_for_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 88</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">endpoint_for</span>( <span class="ruby-identifier">resource</span>, <span class="ruby-identifier">version</span>, <span class="ruby-identifier">options</span> )
  <span class="ruby-identifier">discoverer</span>       = <span class="ruby-identifier">options</span>.<span class="ruby-identifier">delete</span>( <span class="ruby-value">:discoverer</span> )
  <span class="ruby-identifier">discovery_result</span> = <span class="ruby-identifier">discoverer</span>.<span class="ruby-identifier">discover</span>( <span class="ruby-identifier">resource</span>.<span class="ruby-identifier">to_sym</span>, <span class="ruby-identifier">version</span>.<span class="ruby-identifier">to_i</span> )

  <span class="ruby-identifier">klass</span> = <span class="ruby-keyword">if</span> <span class="ruby-identifier">discovery_result</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Services</span><span class="ruby-operator">::</span><span class="ruby-constant">Discovery</span><span class="ruby-operator">::</span><span class="ruby-constant">ForHTTP</span> )
    <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Client</span><span class="ruby-operator">::</span><span class="ruby-constant">Endpoint</span><span class="ruby-operator">::</span><span class="ruby-constant">HTTP</span>
  <span class="ruby-keyword">elsif</span> <span class="ruby-identifier">discovery_result</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Services</span><span class="ruby-operator">::</span><span class="ruby-constant">Discovery</span><span class="ruby-operator">::</span><span class="ruby-constant">ForAMQP</span> )
    <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Client</span><span class="ruby-operator">::</span><span class="ruby-constant">Endpoint</span><span class="ruby-operator">::</span><span class="ruby-constant">AMQP</span>
  <span class="ruby-keyword">elsif</span> <span class="ruby-identifier">discovery_result</span>.<span class="ruby-identifier">nil?</span>
    <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Client</span><span class="ruby-operator">::</span><span class="ruby-constant">Endpoint</span><span class="ruby-operator">::</span><span class="ruby-constant">NotFound</span>
  <span class="ruby-keyword">else</span>
    <span class="ruby-keyword">nil</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-identifier">options</span>[ <span class="ruby-value">:discovery_result</span> ] = <span class="ruby-identifier">discovery_result</span>

  <span class="ruby-keyword">if</span> <span class="ruby-identifier">klass</span>.<span class="ruby-identifier">nil?</span>
    <span class="ruby-identifier">raise</span> <span class="ruby-node">&quot;Hoodoo::Client::Endpoint::endpoint_for: Unrecognised discoverer result class of &#39;#{ discovery_result.class.name }&#39;&quot;</span>
  <span class="ruby-keyword">else</span>
    <span class="ruby-keyword">return</span> <span class="ruby-identifier">klass</span>.<span class="ruby-identifier">new</span>( <span class="ruby-identifier">resource</span>, <span class="ruby-identifier">version</span>, <span class="ruby-identifier">options</span> )
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-new">
              <b>new</b>( resource, version = 1, options )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-c-new" name="method-c-new" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Create an endpoint instance that will be used to make requests to a given
resource.</p>
<dl class="rdoc-list note-list"><dt>resource
<dd>
<p>Resource name the endpoint targets, e.g. <code>:Purchase</code>. String or
symbol.</p>
</dd><dt><code>version</code>
<dd>
<p>Optional required interface (API) version for that endpoint. Integer.
Default is 1.</p>
</dd><dt><code>options</code>
<dd>
<p>Options Hash. Options are described below. Note that this Hash may be
modified during processing.</p>
</dd></dl>

<p>Items in the options hash are required, unless explicitly listed as
optional. They are:</p>
<dl class="rdoc-list note-list"><dt><code>discovery_result</code>
<dd>
<p>A <a href="../Services/Discovery.html">Hoodoo::Services::Discovery</a>
“For…” family member instance, e.g. a <a
href="../Services/Discovery/ForHTTP.html">Hoodoo::Services::Discovery::ForHTTP</a>
instance. Each subclass describes its required discovery result type, so
see its documentation for details.</p>
</dd><dt><code>interaction</code>
<dd>
<p>As in the options for endpoint_for.</p>
</dd><dt><code>session_id</code>
<dd>
<p>As in the options for endpoint_for.</p>
</dd><dt><code>locale</code>
<dd>
<p>As in the options for endpoint_for.</p>
</dd><dt>OTHERS
<dd>
<p>See Hoodoo::Client::Headers&#39; <code>HEADER_TO_PROPERTY</code>. All such
option keys <em>MUST</em> be Symbols.</p>
</dd></dl>

<p>The out-of-the box initialiser sets up the data for the <a
href="Endpoint.html#attribute-i-resource">resource</a>, <a
href="Endpoint.html#attribute-i-version">version</a>, discovery_result, <a
href="Endpoint.html#attribute-i-interaction">interaction</a>, <a
href="Endpoint.html#attribute-i-session_id">session_id</a>, <a
href="Endpoint.html#attribute-i-locale">locale</a>, dated_at and dated_from
accessors using this data, so subclass authors don&#39;t need to.</p>

<p>The endpoint is then used with <a
href="Endpoint.html#method-i-list">list</a>, <a
href="Endpoint.html#method-i-show">show</a>, <a
href="Endpoint.html#method-i-create">create</a>, <a
href="Endpoint.html#method-i-update">update</a> or <a
href="Endpoint.html#method-i-delete">delete</a> methods to perform
operations on the target resource. See each of those methods for details of
their specific requirements; however all have common parameters some or all
of which are used across the method &#39;family&#39;:</p>
<dl class="rdoc-list note-list"><dt><code>ident</code>
<dd>
<p>Identifier. This is usually a <a href="../UUID.html">UUID</a> but some
Resources support e.g. a “show” action based on either a <a
href="../UUID.html">UUID</a> or some other unique value (such as a product
code, a credit/debit card number or so-on - defined by the Resource in
question in its documentation).</p>
</dd><dt><code>query_hash</code>
<dd>
<p>A hash of <em>unencoded</em> data that can be encoded to form a query
string. Search and filter data is represented with nested hashes. Embed and
reference data uses an array. Example:</p>

<pre><code>{
  offset:    75,
  limit:     50,
  sort:      &#39;created_at&#39;, # ...or an Array of sort fields
  direction: &#39;asc&#39;,        # ...or a matching Array of directions
  search:    {
    member_id: &quot;...some UUID...&quot;
  },
  _embed:    [
    &#39;vouchers&#39;,
    &#39;balances&#39;
  ],
  # and/or ...filter: {}..., _reference: []...
}
</code></pre>

<p>This parameter is always optional.</p>
</dd><dt><code>body_hash</code>
<dd>
<p>The Hash representation of the body data that might be sent in an <a
href="Endpoint/HTTP.html">HTTP</a> request (i.e. JSON, as a Hash).</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-new_source')" id="l_method-c-new_source">show</a>
              </p>
              <div id="method-c-new_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 214</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">initialize</span>( <span class="ruby-identifier">resource</span>, <span class="ruby-identifier">version</span> = <span class="ruby-number">1</span>, <span class="ruby-identifier">options</span> )
  <span class="ruby-ivar">@resource</span>         = <span class="ruby-identifier">resource</span>.<span class="ruby-identifier">to_sym</span>
  <span class="ruby-ivar">@version</span>          = <span class="ruby-identifier">version</span>.<span class="ruby-identifier">to_i</span>

  <span class="ruby-ivar">@discovery_result</span> = <span class="ruby-identifier">options</span>[ <span class="ruby-value">:discovery_result</span> ]
  <span class="ruby-ivar">@interaction</span>      = <span class="ruby-identifier">options</span>[ <span class="ruby-value">:interaction</span>      ]

  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">session_id</span>   = <span class="ruby-identifier">options</span>[ <span class="ruby-value">:session_id</span> ]
  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">locale</span>       = <span class="ruby-identifier">options</span>[ <span class="ruby-value">:locale</span>     ]

  <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Client</span><span class="ruby-operator">::</span><span class="ruby-constant">Headers</span><span class="ruby-operator">::</span><span class="ruby-constant">HEADER_TO_PROPERTY</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">rack_header</span>, <span class="ruby-identifier">description</span> <span class="ruby-operator">|</span>
    <span class="ruby-identifier">property</span>        = <span class="ruby-identifier">description</span>[ <span class="ruby-value">:property</span>        ]
    <span class="ruby-identifier">property_writer</span> = <span class="ruby-identifier">description</span>[ <span class="ruby-value">:property_writer</span> ]

    <span class="ruby-keyword">self</span>.<span class="ruby-identifier">send</span>( <span class="ruby-identifier">property_writer</span>, <span class="ruby-identifier">options</span>[ <span class="ruby-identifier">property</span> ] ) <span class="ruby-keyword">if</span> <span class="ruby-identifier">options</span>.<span class="ruby-identifier">has_key?</span>( <span class="ruby-identifier">property</span> )
  <span class="ruby-keyword">end</span>

  <span class="ruby-identifier">configure_with</span>( <span class="ruby-ivar">@resource</span>, <span class="ruby-ivar">@version</span>, <span class="ruby-identifier">options</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
      <div class="sectiontitle">Instance Public methods</div>
        <div class="method">
          <div class="title method-title" id="method-i-create">
              <b>create</b>( body_hash, query_hash = nil )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-i-create" name="method-i-create" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Create a resource instance.</p>
<dl class="rdoc-list note-list"><dt>body_hash
<dd>
<p>See the constructor for details.</p>
</dd><dt>query_hash
<dd>
<p>See the constructor for details.</p>
</dd></dl>

<p>Returns a <a href="AugmentedHash.html">Hoodoo::Client::AugmentedHash</a>
representation of the new resource instance.</p>

<p>Call <a
href="AugmentedBase.html#method-i-platform_errors">Hoodoo::Client::AugmentedBase#platform_errors</a>
(or for service authors implementing resource endpoints, possibly call <a
href="AugmentedBase.html#method-i-adds_errors_to-3F">Hoodoo::Client::AugmentedBase#adds_errors_to?</a>
instead) on the returned instance to detect and resolve error conditions
<em>before</em> examining its Hash-derived fields.</p>

<p>The hash contents are undefined when errors are returned.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-create_source')" id="l_method-i-create_source">show</a>
              </p>
              <div id="method-i-create_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 412</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">create</span>( <span class="ruby-identifier">body_hash</span>, <span class="ruby-identifier">query_hash</span> = <span class="ruby-keyword">nil</span> )
  <span class="ruby-identifier">raise</span> <span class="ruby-string">&quot;Subclasses must implement Hoodoo::Client::Endpoint\#create&quot;</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-delete">
              <b>delete</b>( ident, query_hash = nil )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-i-delete" name="method-i-delete" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Delete a resource instance.</p>
<dl class="rdoc-list note-list"><dt>ident
<dd>
<p>See the constructor for details.</p>
</dd><dt>query_hash
<dd>
<p>See the constructor for details.</p>
</dd></dl>

<p>Returns a <a href="AugmentedHash.html">Hoodoo::Client::AugmentedHash</a>
representation of the now-deleted resource instance,from the instant before
deletion.</p>

<p>Call <a
href="AugmentedBase.html#method-i-platform_errors">Hoodoo::Client::AugmentedBase#platform_errors</a>
(or for service authors implementing resource endpoints, possibly call <a
href="AugmentedBase.html#method-i-adds_errors_to-3F">Hoodoo::Client::AugmentedBase#adds_errors_to?</a>
instead) on the returned instance to detect and resolve error conditions
<em>before</em> examining its Hash-derived fields.</p>

<p>The hash contents are undefined when errors are returned.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-delete_source')" id="l_method-i-delete_source">show</a>
              </p>
              <div id="method-i-delete_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 453</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">delete</span>( <span class="ruby-identifier">ident</span>, <span class="ruby-identifier">query_hash</span> = <span class="ruby-keyword">nil</span> )
  <span class="ruby-identifier">raise</span> <span class="ruby-string">&quot;Subclasses must implement Hoodoo::Client::Endpoint\#delete&quot;</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-list">
              <b>list</b>( query_hash = nil )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-i-list" name="method-i-list" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Obtain a list of resource instance representations.</p>
<dl class="rdoc-list note-list"><dt>query_hash
<dd>
<p>See the constructor for more. This is the only way to search or filter the
list, via the target Resource&#39;s documented supported search/filter
parameters and the platform&#39;s common all-Resources behaviour.</p>
</dd></dl>

<p>Returns a <a href="AugmentedArray.html">Hoodoo::Client::AugmentedArray</a>
representation of the requested list of resource instances.</p>

<p>Call <a
href="AugmentedBase.html#method-i-platform_errors">Hoodoo::Client::AugmentedBase#platform_errors</a>
(or for service authors implementing resource endpoints, possibly call <a
href="AugmentedBase.html#method-i-adds_errors_to-3F">Hoodoo::Client::AugmentedBase#adds_errors_to?</a>
instead) on the returned instance to detect and resolve error conditions
<em>before</em> examining its Array-derived contents.</p>

<p>The array will be empty in successful responses if no items satisfying the
list conditions were found. The array contents are undefined in the case of
errors.</p>

<p>Call <a
href="PaginatedEnumeration.html#method-i-enumerate_all">Hoodoo::Client::PaginatedEnumeration#enumerate_all</a>
to enumerate over the list of resource instances with automatic pagination.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-list_source')" id="l_method-i-list_source">show</a>
              </p>
              <div id="method-i-list_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 372</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">list</span>( <span class="ruby-identifier">query_hash</span> = <span class="ruby-keyword">nil</span> )
  <span class="ruby-identifier">raise</span> <span class="ruby-string">&quot;Subclasses must implement Hoodoo::Client::Endpoint\#list&quot;</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-show">
              <b>show</b>( ident, query_hash = nil )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-i-show" name="method-i-show" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Obtain a resource instance representation.</p>
<dl class="rdoc-list note-list"><dt>ident
<dd>
<p>See the constructor for details.</p>
</dd><dt>query_hash
<dd>
<p>See the constructor for details.</p>
</dd></dl>

<p>Returns a <a href="AugmentedHash.html">Hoodoo::Client::AugmentedHash</a>
representation of the requested resource instance.</p>

<p>Call <a
href="AugmentedBase.html#method-i-platform_errors">Hoodoo::Client::AugmentedBase#platform_errors</a>
(or for service authors implementing resource endpoints, possibly call <a
href="AugmentedBase.html#method-i-adds_errors_to-3F">Hoodoo::Client::AugmentedBase#adds_errors_to?</a>
instead) on the returned instance to detect and resolve error conditions
<em>before</em> examining its Hash-derived fields.</p>

<p>The hash contents are undefined when errors are returned.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-show_source')" id="l_method-i-show_source">show</a>
              </p>
              <div id="method-i-show_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 392</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">show</span>( <span class="ruby-identifier">ident</span>, <span class="ruby-identifier">query_hash</span> = <span class="ruby-keyword">nil</span> )
  <span class="ruby-identifier">raise</span> <span class="ruby-string">&quot;Subclasses must implement Hoodoo::Client::Endpoint\#show&quot;</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-update">
              <b>update</b>( ident, body_hash, query_hash = nil )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-i-update" name="method-i-update" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Update a resource instance.</p>
<dl class="rdoc-list note-list"><dt>ident
<dd>
<p>See the constructor for details.</p>
</dd><dt>body_hash
<dd>
<p>See the constructor for details.</p>
</dd><dt><code>query_hash</code>
<dd>
<p>See the constructor for details.</p>
</dd></dl>

<p>Returns a <a href="AugmentedHash.html">Hoodoo::Client::AugmentedHash</a>
representation of the updated resource instance.</p>

<p>Call <a
href="AugmentedBase.html#method-i-platform_errors">Hoodoo::Client::AugmentedBase#platform_errors</a>
(or for service authors implementing resource endpoints, possibly call <a
href="AugmentedBase.html#method-i-adds_errors_to-3F">Hoodoo::Client::AugmentedBase#adds_errors_to?</a>
instead) on the returned instance to detect and resolve error conditions
<em>before</em> examining its Hash-derived fields.</p>

<p>The hash contents are undefined when errors are returned.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-update_source')" id="l_method-i-update_source">show</a>
              </p>
              <div id="method-i-update_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 433</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">update</span>( <span class="ruby-identifier">ident</span>, <span class="ruby-identifier">body_hash</span>, <span class="ruby-identifier">query_hash</span> = <span class="ruby-keyword">nil</span> )
  <span class="ruby-identifier">raise</span> <span class="ruby-string">&quot;Subclasses must implement Hoodoo::Client::Endpoint\#update&quot;</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
      <div class="sectiontitle">Instance Protected methods</div>
        <div class="method">
          <div class="title method-title" id="method-i-configure_with">
              <b>configure_with</b>( resource, version, options )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-i-configure_with" name="method-i-configure_with" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>This protected method is implemented by subclasses and called from the
initializer. Subclasses should store resource and version data however they
want and validate any required options, raising errors if need be.</p>
<dl class="rdoc-list note-list"><dt><code>resource</code>
<dd>
<p>Resource name the endpoint targets, e.g. <code>:Purchase</code>. Symbol.</p>
</dd><dt><code>version</code>
<dd>
<p>Optional required interface (API) version for that endpoint. Integer.</p>
</dd><dt><code>options</code>
<dd>
<p>Options Hash. Same as for initialize.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-configure_with_source')" id="l_method-i-configure_with_source">show</a>
              </p>
              <div id="method-i-configure_with_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 253</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">configure_with</span>( <span class="ruby-identifier">resource</span>, <span class="ruby-identifier">version</span>, <span class="ruby-identifier">options</span> )
  <span class="ruby-identifier">raise</span> <span class="ruby-string">&quot;Subclasses must implement Hoodoo::Client::Endpoint\#configure_with&quot;</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-copy_updated_options_to">
              <b>copy_updated_options_to</b>( target_endpoint )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-i-copy_updated_options_to" name="method-i-copy_updated_options_to" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Copy the current value of writable options in this <a
href="Endpoint.html">Endpoint</a> instance, to another <a
href="Endpoint.html">Endpoint</a> instance. This is useful when one is
wrapping another, but to the external user of the wrapping endpoint, they
should just be able to set options in that item and have it act as if
they&#39;d set them on the thing which it is (not that the caller would
know) wrapping.</p>

<p>This includes copying over a <code>session_id</code> field value, though
often it&#39;ll subsequently be rewritten by the wrapping endpoint as
it&#39;s wrapping something to provide special session management.</p>

<p>WARNING: Any <code>nil</code> internal state values will <em>not</em> be
copied.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-copy_updated_options_to_source')" id="l_method-i-copy_updated_options_to_source">show</a>
              </p>
              <div id="method-i-copy_updated_options_to_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 303</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">copy_updated_options_to</span>( <span class="ruby-identifier">target_endpoint</span> )
  <span class="ruby-identifier">target_endpoint</span>.<span class="ruby-identifier">session_id</span> = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">session_id</span> <span class="ruby-keyword">unless</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">session_id</span>.<span class="ruby-identifier">nil?</span>
  <span class="ruby-identifier">target_endpoint</span>.<span class="ruby-identifier">locale</span>     = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">locale</span>     <span class="ruby-keyword">unless</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">locale</span>.<span class="ruby-identifier">nil?</span>

  <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Client</span><span class="ruby-operator">::</span><span class="ruby-constant">Headers</span><span class="ruby-operator">::</span><span class="ruby-constant">HEADER_TO_PROPERTY</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">rack_header</span>, <span class="ruby-identifier">description</span> <span class="ruby-operator">|</span>
    <span class="ruby-identifier">property</span>        = <span class="ruby-identifier">description</span>[ <span class="ruby-value">:property</span>        ]
    <span class="ruby-identifier">property_writer</span> = <span class="ruby-identifier">description</span>[ <span class="ruby-value">:property_writer</span> ]

    <span class="ruby-identifier">value</span> = <span class="ruby-keyword">self</span>.<span class="ruby-identifier">send</span>( <span class="ruby-identifier">property</span> )

    <span class="ruby-identifier">target_endpoint</span>.<span class="ruby-identifier">send</span>( <span class="ruby-identifier">property_writer</span>, <span class="ruby-identifier">value</span> ) <span class="ruby-keyword">unless</span> <span class="ruby-identifier">value</span>.<span class="ruby-identifier">nil?</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-generate_404_response_for">
              <b>generate_404_response_for</b>( action )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-i-generate_404_response_for" name="method-i-generate_404_response_for" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Utility method to aid subclass authors. Not usually overridden.</p>

<p>Return an instance of <a
href="AugmentedArray.html">Hoodoo::Client::AugmentedArray</a> or <a
href="AugmentedHash.html">Hoodoo::Client::AugmentedHash</a> with an
associated 404 error (as a fully formed platform error) describing &#39;Not
Found&#39; for the target resource, version and given action.</p>
<dl class="rdoc-list note-list"><dt><code>action</code>
<dd>
<p>A Symbol from Hoodoo::Services::Middleware::ALLOWED_ACTIONS.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-generate_404_response_for_source')" id="l_method-i-generate_404_response_for_source">show</a>
              </p>
              <div id="method-i-generate_404_response_for_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 280</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">generate_404_response_for</span>( <span class="ruby-identifier">action</span> )
  <span class="ruby-identifier">data</span> = <span class="ruby-identifier">response_class_for</span>( <span class="ruby-identifier">action</span> ).<span class="ruby-identifier">new</span>
  <span class="ruby-identifier">data</span>.<span class="ruby-identifier">platform_errors</span>.<span class="ruby-identifier">add_error</span>(
    <span class="ruby-string">&#39;platform.not_found&#39;</span>,
    <span class="ruby-string">&#39;reference&#39;</span> =<span class="ruby-operator">&gt;</span> { <span class="ruby-value">:entity_name</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-node">&quot;v#{ @version } of #{ @resource } interface endpoint&quot;</span> }
  )

  <span class="ruby-keyword">return</span> <span class="ruby-identifier">data</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-inject_enumeration_state">
              <b>inject_enumeration_state</b>( augmented_array, query_hash )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-i-inject_enumeration_state" name="method-i-inject_enumeration_state" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Set the <code>augmented_array</code>&#39;s <code>next_page_proc</code>
attribute to a Proc that will call the list endpoint to retrieve the next
batch of of Resources using the same query parameters.</p>
<dl class="rdoc-list note-list"><dt><code>augmented_array</code>
<dd>
<p>The <a href="AugmentedArray.html">Hoodoo::Client::AugmentedArray</a>
instance containing the initial set of Resources to be enumerated through.</p>
</dd><dt><code>query_hash</code>
<dd>
<p>The query parameters to be used for this enumeration. See the constructor
for more.</p>
</dd></dl>

<p>Returns the <code>augmented_array</code> passed in, with the
<code>next_page_proc</code> value set.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-inject_enumeration_state_source')" id="l_method-i-inject_enumeration_state_source">show</a>
              </p>
              <div id="method-i-inject_enumeration_state_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 331</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">inject_enumeration_state</span> ( <span class="ruby-identifier">augmented_array</span>, <span class="ruby-identifier">query_hash</span> )

  <span class="ruby-identifier">endpoint</span>                       = <span class="ruby-keyword">self</span>
  <span class="ruby-identifier">query_hash</span>                     = <span class="ruby-identifier">query_hash</span>.<span class="ruby-identifier">nil?</span> <span class="ruby-operator">?</span> {} <span class="ruby-operator">:</span> <span class="ruby-identifier">query_hash</span>.<span class="ruby-identifier">dup</span>
  <span class="ruby-identifier">batch_size</span>                     = [ <span class="ruby-number">1</span>, <span class="ruby-identifier">augmented_array</span>.<span class="ruby-identifier">size</span> ].<span class="ruby-identifier">max</span>
  <span class="ruby-identifier">augmented_array</span>.<span class="ruby-identifier">next_page_proc</span> = <span class="ruby-constant">Proc</span>.<span class="ruby-identifier">new</span> <span class="ruby-keyword">do</span>
    <span class="ruby-identifier">query_hash</span>[ <span class="ruby-value">:offset</span> ] = ( <span class="ruby-identifier">query_hash</span>[ <span class="ruby-value">:offset</span> ] <span class="ruby-operator">||</span> <span class="ruby-number">0</span> ) <span class="ruby-operator">+</span> <span class="ruby-identifier">batch_size</span>
    <span class="ruby-identifier">endpoint</span>.<span class="ruby-identifier">list</span>( <span class="ruby-identifier">query_hash</span> )
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">return</span> <span class="ruby-identifier">augmented_array</span>

<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-i-response_class_for">
              <b>response_class_for</b>( action )
            <a href="../../../classes/Hoodoo/Client/Endpoint.html#method-i-response_class_for" name="method-i-response_class_for" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Utility method to aid subclass authors. Not usually overridden.</p>

<p>Determine the response class needed for a given action - returns <a
href="AugmentedArray.html">Hoodoo::Client::AugmentedArray</a> or <a
href="AugmentedHash.html">Hoodoo::Client::AugmentedHash</a> (class
references, not instances).</p>
<dl class="rdoc-list note-list"><dt><code>action</code>
<dd>
<p>A Symbol from Hoodoo::Services::Middleware::ALLOWED_ACTIONS.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-i-response_class_for_source')" id="l_method-i-response_class_for_source">show</a>
              </p>
              <div id="method-i-response_class_for_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/client/endpoint/endpoint.rb, line 266</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">response_class_for</span>( <span class="ruby-identifier">action</span> )
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">action</span>.<span class="ruby-identifier">equal?</span>( <span class="ruby-value">:list</span> ) <span class="ruby-operator">?</span> <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Client</span><span class="ruby-operator">::</span><span class="ruby-constant">AugmentedArray</span> <span class="ruby-operator">:</span> <span class="ruby-constant">Hoodoo</span><span class="ruby-operator">::</span><span class="ruby-constant">Client</span><span class="ruby-operator">::</span><span class="ruby-constant">AugmentedHash</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
</div>

    </div>
  </body>
</html>
